.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com>
.\"
.\" SPDX-License-Identifier: LGPL-2.0-or-later
.\"
.TH io_uring_register_buffers 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
.SH NAME
io_uring_register_buffers \- register buffers for fixed buffer operations
.SH SYNOPSIS
.nf
.B #include <liburing.h>
.PP
.BI "int io_uring_register_buffers(struct io_uring *" ring ",
.BI "                              const struct iovec *" iovecs ",
.BI "                              unsigned " nr_iovecs ");"
.PP
.BI "int io_uring_register_buffers_sparse(struct io_uring *" ring ",
.BI "                              unsigned " nr_iovecs ");"
.fi
.SH DESCRIPTION
.PP
The
.BR io_uring_register_buffers (3)
function registers
.I nr_iovecs
number of buffers defined by the array
.I iovecs
belonging to the
.IR ring .

The
.BR io_uring_register_buffers_sparse (3)
function registers
.I nr_iovecs
empty buffers belonging to the
.IR ring .
These buffers must be updated before use, using eg
.BR io_uring_register_buffers_update_tag (3).

After the caller has registered the buffers, they can be used with one of the
fixed buffers functions.

Registered buffers is an optimization that is useful in conjunction with
.B O_DIRECT
reads and writes, where it maps the specified range into the kernel once when
the buffer is registered rather than doing a map and unmap for each IO
every time IO is performed to that region. Additionally, it also avoids
manipulating the page reference counts for each IO.

.SH RETURN VALUE
On success
.BR io_uring_register_buffers (3)
and
.BR io_uring_register_buffers_sparse (3)
return 0. On failure they return
.BR -errno .
.SH SEE ALSO
.BR io_uring_get_sqe (3),
.BR io_uring_unregister_buffers (3),
.BR io_uring_register_buf_ring (3),
.BR io_uring_prep_read_fixed (3),
.BR io_uring_prep_write_fixed (3)
